home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Software Vault: The Gold Collection
/
Software Vault - The Gold Collection (American Databankers) (1993).ISO
/
cdr05
/
ewrtgn10.zip
/
EWRTFGEN.DOC
next >
Wrap
Text File
|
1993-07-17
|
19KB
|
540 lines
EWRTFGEN
An Extension DLL for E! for Windows (EW)
(C) Copyright 1992, by L. David Baldwin
(C) Copyright 1993, by Patrick Philippot
All Rights Reserved
This package contains an adaptation of Dave Baldwin's RTFGEN
program, a utility converting an ASCII file complying to a given
syntax into an RTF file suitable for compilation by the HC, the
Microsoft Windows help compiler.
You cannot use EWRTFGEN is you don't have installed E! for
Windows. E! for Windows is a shareware programmer's text editor
downloadable from the IBMAPP EDITORS library on Compuserve and
from many other BBSs.
During the process of developping EW, I have found RTFGEN so
simple and useful that I have decided to use it to produce the
EW help file.
Once the initial release of EW was ready, I have decided to
integrate RTFGEN into an EW Extension DLL to make it even easier
to use. I gratefully thank David for giving me the authorization
of using his code. EW Extension DLLs are discussed in the
documentation of E! for Windows. This package is a good example of
the power of EW Extension DLLs.
EWRTFGEN may not be have all the bells and whistles of other RTF
generation commercial packages but, after all, the EW Help file has
been constructed with RTFGEN and we think that it will suit the needs
of many programmers.
Most of the code in this package is from Dave. I have just
removed the input routines that were useless since the text was
retrieved from memory directly. I have also modified the Error
routine and added some code to process accented characters. The
translation of RTFGEN into an EW Extension DLL was rather easy
and only took a few hours.
This package is free and will not be included in the EW
distribution package.
EWRTFGEN may be copied and distributed freely providing that no
fee is charged and it is not part of a package for which a
charge is made.
HOW TO USE EWRTFGEN
EWRTFGEN.EWD must be copied to your EW\USER directory. While EW
is running you can load EWRTFGEN from the USER Menu using the
"Load User Extension..." command. Or you can add it to the
Autoload List from the same menu to have it loaded automatically
when EW is run.
Once EWRTFGEN has been loaded, a new item will appear in the
User Menu: "Translate to RTF".
Select this command to begin the process of translating your
RTFGEN source file into a RTF file. The following will occur:
1. The current file is systematically saved to make sure that you
will compile the correct source.
2. The RTF output will be placed in a file in the same directory
as the source file. This file will have the same name as the
source file but with a .RTF extension. At this time you can't
modify this behavior unless you modify the source file. The
Borland Pascal compiler is required to compile EWRTFGEN.
3. Any error will be reported and displayed in the EW Status
window at the bottom of the Edit Window. The caret will point to
the error in the source file.
Your source file is supposed to be compliant to the RTFGEN
syntax described below. The following text is a slightly
modified excerpt of the original RTFGEN documentation.
We hope that this package will be useful to many Windows
developers.
Patrick Philippot
04/10/93
=================================================================
RTFGEN SYNTAX DESCRIPTION
=================================================================
February 22, 1992
RTFGEN
An ASCII to Rich Text Format Conversion Program
Version 1.0
OVERVIEW
Normally, to create a help file with the Windows help compiler,
you must first write a help topic file using a Rich Text Format
(RTF) word processor. For many, there are two problems here:
1. RTF word processors are expensive.
2. Learning to use a new word processor is a nuisance and not
very productive.
RTFGEN solves both these problems by allowing you to use your
favorite ASCII text editor to produce RTF formatted files
acceptable to the help compiler.
STEPS FOR BUILDING A HELP FILE
The steps required to create a Windows help file using EWRTFGEN
are:
1. Using EW, create one or more input text files.
The layout of the input files will be discussed later.
2. Load EWRTFGEN from the User Menu if it has not been
Autoloaded.
3. Run EWRTFGEN by selecting the "Translate to RTF" command
in the User Menu.
4. Create a Help Project File (.HPJ) for input to the help
compiler. This file should reference the RTF files.
5. Run the help compiler to make the help file.
Steps 4 and 5 are described in the help compiler documentation.
This documentation deals with the first three steps only.
GENERAL EDITING CONSIDERATIONS
The use of tabs is required to obtain column alignment with
proportional fonts. The RTF command, \tab, may be used to
produce tabs (remember that EW automatically expands tabs to
spaces).
Here are the default conditions use by RTFGEN:
Helv, 10 point font.
Paragraphs are left justified. The first line is not
indented.
Paragraph indentation is set by indentation of the first
line of the paragraph.
Tabs are spaced every 720 twips (about 6 default
characters).
Any of these defaults may be changed globally for the whole
document or locally at the topic, paragraph, or even character
level.
RTFGEN and/or the RTF language have special use for the
following characters:
` (grave accent) Used to mark end of paragraphs.
[,] Used to mark jumps and definitions.
{,} Used to mark areas where font characteristics will change.
\ Used as a command start character.
When these characters are to be used in the text, they should be
preceded by a '\'. Thus, '\[' will cause the left bracket to be
inserted in text and '\\' will result in a single backslash
being inserted in text.
(*...*) may be used to insert comments within the text.
ASCII INPUT FILE LAYOUT
The input file for RTFGEN should have the following sections:
1. An optional document header.
2. The command, \docstart, to mark the start of the document.
3. One or more topics consisting of:
a. A topic header.
b. A row of 5 or more '='s marking the start of the topic
text.
c. The topic text. This is basically the text to be
displayed in the help file.
d. A row of 5 or more '-'s marking the end of the topic.
4. The command, \docend, marking the end of the document.
Document Header
The optional document header may contain commands which will be
interpreted globally throughout the document. Commands changing
the font, font size, or first line indent might be appropriate
here.
The \docstart command follows the document header to mark the
start of the topics.
Example:
\f0 \fs24 (*Times Roman font, 12 pitch for entire file*)
\docstart
Topic Header
The topic header contains commands defining build tags, context
strings, title, keywords, and browse sequence number as
appropriate for the topic. Topic global formatting commands may
also be included. The topic header section is terminated with a
row of 5 or more '='s.
Example:
\title Table of Contents`
\topic contents`
\keyword contents`
\f0 \fs24 (* Times Roman font, 12 pitch for this topic *)
============ (* end of topic header *)
Topic Text
Text for the topic is entered here. Rules for text entry are:
Paragraph ends are marked with a grave accent, '`'
Blank lines will appear as blank lines.
By default, paragraphs are left justified. The indenting of the
paragraph is set by the indenting of the first line of the
paragraph. Indenting of lines after the first is ignored.
Carriage returns and linefeeds within the paragraph are ignored
as far as the final results are concerned.
Commands may be interspersed within the text for special
effects. The commands themselves won't appear in the final
result.
Examples:
| Here is a typical paragraph. It will appear in the font
| and pitch specified in the topic header or document
| header. It is left justified and indented by 360 twips
| because the first line is so indented. The paragraph
| is terminated with a grave accent character.`
| \b\fi480 Here is another paragraph. It will appear in
| bold font because of the \b command. It will also be
| be indented by 360 twips and left justified. The
| \fi480 will cause the first line of the paragraph
| to be indented an additional 480 twips.`
COMMAND SYNTAX
Commands for RTFGEN and RTF commands passed thru to the help
compiler have a similar syntax. Commands start with a backslash
followed by a LOWERCASE alpha symbol. Some RTF commands have a
numerical value attached. Some RTFGEN commands have an
additional parameter string.
Examples:
\box
\topic <topic name>
\fs24 RTF command with number
\fi-720 '-' sign may be used if appropriate
When commands are mixed with text, a trailing space may be
required as a delimiter. The first space following a command is
considered part of the command--additional spaces are part of
the text.
RTFGEN COMMANDS
Topic Header Commands
\buildtag <parameter string>`
\topic <parameter string>`
\title <parameter string>`
\keyword <parameter string>`
\browse <parameter string>`
These commands correspond to the *, #, $, K, and + footnotes
described in the help compiler documentation. Each topic header
will contains one or more of these commands as appropriate
(ordering is unimportant).
The parameter string should--
have format and contents exactly as described in the help
compiler documentation for the equivalent footnote.
be entirely on one line.
be terminated by an end of paragraph mark (grave accent).
More than one \keyword command may be used if the number of
keywords would exceed the allowable editor line length.
Examples:
\topic proc_deleting_text`
\title Deleting Text`
\browse procedures:020`
\keyword delete;clipboard`
Cross References
Cross references may be included in the topic text using the
format:
[<green text>:<context>]
where the brackets indicate a cross reference, <green text> will
appear highlighted, and <context> is the topic context string
for the jump destination.
Example:
To change the color of an existing object, the object is first
[selected:selecting]. Its color may then be changed.`
Definitions
Definitions may also be included in topic text by enclosing them
in double brackets:
[[<green text>:<context>]]
Example:
Each space is equivalent to 120 [[twips:twip_def]].`
Bitmap Commands
\bml <filename>
\bmr <filename>
\bmc <filename>
These commands are used to insert bitmaps within the topic text.
Example:
A bitmap may be placed in a sentence \bmc arrow.bmp , just like
any character.`
It's also possible to use a bitmap to cause a jump or bring up a
definition as:
Press here [\bmc button.bmp:jump_dest] for more information.`
Block Formatting Commands
\blockstart <commands>`
\blockend
The blockstart, blockend commands define a block over which a
set of RTF commands will apply. These commands are used mainly
when laying out tables where formatting is somewhat complex. An
example of their use is given later in the tabbing commands
section.
The block formatting commands may be nested to a level of 4.
RTF COMMANDS
RTF commands have no effect on RTFGEN but rather are passed
along to the help compiler to achieve certain effects.
In the following, some of the RTF commands which seem
appropriate for use in help files are listed. While there are a
good many listed, keep in mind that in most help files only a
few will be required.
Font Commands
Fonts are refered to by number. Number vs font is set by the
font table in the HEADING file. For the HEADING file supplied:
0 Times Roman
1 Symbol
2 Helv (default)
3 Courier
You can add fonts or change the order by editing the HEADING
file.
\f000 change to font 000
\fs000 set font size in half points
\plain plain text (as opposed to bold, italic)
\b bold
\i italic
\ul underline
\uldb double underline
\uld dotted underline
\strike strikethru text
The scope of font commands may be document global (placed in
document header), topic global (placed in topic header),
paragraph global (placed at start of paragraph), or character or
word global (scope defined with {..}).
Examples:
\b This paragraph will appear in bold text.`
This paragraph is {\ul mostly} in plain text with a {\b bold}
and an {\i italicized} word. {\f0 Fonts and \fs30 pitch} can be
temporarily changed.`
Paragraph Commands
\par end of paragraph. RTFGEN handles this.
\pard reset to paragraph defaults. RTFGEN handles
this.
\li000 left paragraph indent in twips. RTFGEN
handles this.
\fi000 first line indent. May be negative.
\ri000 right paragraph indent.
\sb000 space below paragraph.
\sa000 space above paragraph.
\ql left justified (default)
\qc paragraph is centered
\qr right justified
\box paragraph is surrounded by a box
\brdrl left border
\brdrb bottom border
\brdrr right border
\brdrt top border
The scope of paragraph commands may be document global (placed
in the document header), topic global (placed in the topic
header), or paragraph global (placed at the start of the
paragraph).
Examples:
|\box\qc This paragraph is surrounded by a box and is centered.`
| \fi-360 The first line of this paragraph overhangs by
| about 3 characters. Note that RTFGEN has already
| indented the paragraph 720 twips because of its
| interpretation of
| the 6 character indentation on the first line.`
Tabbing Commands
In RTFGEN, either the tab character or the RTF command, \tab,
may be used to produce a tab in the help file. By default, tabs
are every 720 twips (about 6 characters). If neat columns are
desired with proportional fonts, tabs are a must.
\tab causes tab
\tx0000 defines tab position in twips. May be used
multiply and should be used prior to using
tabs.
The following should be used just prior to the \tx000 command to
which they are to apply:
\tqr tab is right justified
\tqc tab is centered
The \blockstart..\blockend commands may be used to prepare the
format for a table.
Example:
\blockstart \li1000\tqr\tx2700\tqc\tx4000` (* tab setup *)
\ul Left\tab Right\tab Centered` (* underlined table heading *)
Data1\tab 1234\tab 12345`
ABC \tab 12\tab 3333444`
XYZdef\tab 45678\tab 9`
\blockend
SOURCE CODE
The cosurce code is provided for those who may want to modify the
package themselves. It's also a good example of EW Extension DLL.
Please don't upload a modified package without notifying us.
The EW API documentation is available for EW registered users only.
REFERENCES
The following files may be found on CompuServe in several
locations. To find them use the IBM file finder (GO IBMFF).
RTF.TXT Info on the RTF syntax. Many more commands
are listed than given here.
QDHELP.LZH Another system to produce help files using an
ASCII editor.
COPYRIGHT
Original RTFGEN package:
(C) Copyright 1992 by L. David Baldwin.
All Rights Reserved
EWRTFGEN
(C) Copyright 1993 by Patrick Philippot.
All Rights Reserved
EWRTFGEN may be copied and distributed freely providing that no
fee is charged and it is not part of a package for which a
charge is made.
Please report all bugs, suggestions, and problems to Dave
Baldwin, CompuServe ID #76327, 53. However, problems related to
EWRTFGEN itself (that is, problems not related to the RTF code
generation) have to be reported to Patrick Philippot, Compuserve
ID #72561,3532.